home *** CD-ROM | disk | FTP | other *** search
/ Creative Computers / Creative Computers CD-ROM, Volume 1 (Legendary Design Technologies, Inc.)(1994).iso / shareware / menu / addtools_1.11 / addtoolsdoc-e < prev    next >
Text File  |  1994-11-17  |  15KB  |  334 lines
  1. $VER: AddTools.doc 1.11 (10.8.93) © Alessandro Sala
  2.  
  3.                     AddTools version 1.11 10-Aug-1993
  4.                    Copyright © 1993 By Alessandro Sala
  5.  
  6.              Requires AmigaOS v2.04 ( Kickstart v37 ) or later
  7.  
  8.  
  9.                                ------------
  10.                                 Disclaimer
  11.                                ------------
  12.  
  13.    This program is provided "as is" without warranty of any kind, either
  14. expressed or implied, including, but not limited to, the implied warranty
  15. of fitness for a particular purpose.  Though every care has been taken to
  16. make this program system-friendly and bugs-free, the entire risk as to the
  17. results, reliability and performance of this program is assumed by you.
  18.  
  19.  
  20.                             ------------------
  21.                              Copyright notice
  22.                             ------------------
  23.  
  24.    This program is "FreeWare": it can be freely copied and distributed for
  25. non-commercial purposes, provided that no file is added to or removed from the
  26. distribution archive and no charge, beside a nominal media cost, is requested.
  27.    Nevertheless the program remains COPYRIGHT of the Author: you cannot
  28. patch, reverse engineer or otherwise modify the program, the documentation and
  29. every other file found in the distribution archive.
  30.    Compressing in executable form is only allowed for personal use, not
  31. when the program is being distributed: LHARC'ing in an archival form is
  32. explicitly allowed for distribution convenience.
  33.    Furthermore you cannot embed the program in any other software without
  34. the written permission of the author.
  35.  
  36.                      ------------------------------------
  37.                      Contents of the distribution archive
  38.                      ------------------------------------
  39.  
  40.     AddTools                 : The main program
  41.     AddToolsData             : Configuration file example
  42.     AddToolsDoc-E            : English documentation
  43.     Catalogs                 : Drawer
  44.       AddTools.ct            : Empty translation file
  45.       italiano               : Drawer
  46.         AddTools.catalog     : Italian language support file
  47.     MTCopy                   : Example of AmigaDos script for use with AddTools
  48.  
  49.     AddTools.info           \
  50.     AddToolsData.info        |
  51.     AddToolsDoc-E.info       |       : Related icons
  52.     Catalogs.info            |
  53.       AddTools.ct.info       |
  54.     MTCopy.info             /
  55.  
  56.  
  57.                              1. Introduction
  58.                              ---------------
  59.  
  60.    AddTools is a very simple utility, written mainly to experiment with the
  61. new applications menu ( "Tools" ) of AmigaOS release 2, but I found it very
  62. useful so I decided to release it as Freeware with the hope that someone
  63. else will find it convenient.
  64.    The program allows you to add your own items to the "Tools" menu of
  65. AmigaOS_2.04's Workbench Screen. Unlike other menu utilities, which only add
  66. the ability to run programs by menu, AddTools can also pass them some
  67. parameters on "the fly" in the form of icons ( from now on called " icon
  68. parameters" ), selected before choosing the desired menu item. You can also
  69. provide default values if no icons are selected, and you can decide if the
  70. the program must be run in either synchronous or asynchronous mode when
  71. multiple icon parameters are selected.
  72.  
  73.                          --------------------------
  74.                          Changes since version 1.00
  75.                          --------------------------
  76.  
  77.    If you already know AddTools, here are some major differences from the
  78. previous version:
  79.  
  80.   --  The limit of 10 menu items has been removed.
  81.  
  82.   --  Using synchronous items no longer locks AddTools until all parameters have
  83. been processed. Now there is an independent task handling synchronous items.
  84.  
  85.  
  86.   --  Now supports localization if you have OS 2.1 or later; currently
  87. supported languages are:
  88.                          English (built-in)
  89.                          Italian
  90.  
  91.       To use a language different from english you need the 'AddTools.catalog'
  92. file for that language in your 'SYS:Locale/catalogs/<language>/' directory
  93. or in 'catalogs/<language>/' inside AddTools directory.
  94.  
  95.  
  96.   --  If you choose an item with less than 2 icons selected ( that is 1 or
  97. none ) it will now run in asynchronous mode regardless of the sync/async
  98. flag.
  99.  
  100.  
  101.   --  There is now a new menu item, named 'AddTools...', which is
  102. automatically added at the end of user items. Selecting 'AddTools...' you
  103. will see a requester asking you if you want to quit the program.
  104.  
  105.  
  106.   --  Fixed a bug in icon parameters handling code: if an item had default
  107. parameters inside the '[]', the command line after the ']' was ignored: now
  108. it's ok.
  109.  
  110.  
  111.   --  Now supports multiple '[<default_params>]' strings in a single command
  112. line.
  113.  
  114.  
  115.                                 ------------
  116.                                 Installation
  117.                                 ------------
  118.  
  119.    To install AddTools you can simply copy it in some drawer, typically
  120. your SYS:WBStartup drawer. Then create the configuration file AddToolsData, as
  121. explained below, and put it in your S: volume ( normally the SYS:S drawer ) or
  122. in the same directory as AddTools. If you have OS 2.1 or later and you want to
  123. take advantage of the localization, you must also copy the 'catalogs' drawer,
  124. found in the AddTools distribution archive, into the same drawer as AddTools,
  125. or you can copy the 'AddTools.catalog' file ( found in the 'catalogs/<language>/'
  126. drawer ) into your 'LOCALE:catalogs/<language>/' drawer.
  127.    If your language is not currently available, you can fill in the empty
  128. translation file found in the catalogs drawer ( catalogs/AddTools.ct ) and
  129. send it to me by E-Mail ( the address is at the end of this file ). I will
  130. create a new '<your-language>/AddTools.catalog' file and E-Mail it to you as
  131. soon as possible, and the next version of AddTools will support one more
  132. language !
  133.  
  134.  
  135.                          2. Configuration and usage
  136.                          --------------------------
  137.  
  138.  
  139. -2.1- The configuration file
  140.  
  141.    AddTools can be started from workbench by double-clicking its icon or by
  142. placing it in your WBStartup drawer to have it activated every time you
  143. boot; in this case remember to add the "DONOTWAIT" ToolType.
  144.    You can also run AddTools from a CLI or from your user-startup; in this
  145. case use the RUN command to start AddTools in the background.
  146.    When AddTools is started, it looks in the current directory to see if a
  147. configuration file named "AddToolsData" exists: if not, it then searches
  148. in the S: volume (typically your SYS:S drawer) and aborts if it doesn't find
  149. there the configuration file.
  150.    The "AddToolsData" file contains the description of the various menu items
  151. you want to add to the Tools menu. Every item is defined by three lines with
  152. the following format:
  153.  
  154.       <Line 1>    Menu_item_text
  155.       <Line 2>    Menu_item_associated_command_line_with_parameters
  156.       <Line 3>    Synchronous/Asynchronous_mode_flag
  157.  
  158. these three lines are repeated for every menu item you want to add. Here
  159. comes an explanation of every line:
  160.  
  161.    Line 1 : Menu item text :   This is the text you want to be displayed in
  162.                              the tools menu: note that shortcuts are not
  163.                              available at the moment.
  164.  
  165.  
  166.    Line 2 : Command line   :   This will normally be the complete path and
  167.                              name of the program you want to be run when
  168.                              choosing this menu item, possibly followed by
  169.                              parameters. If you want to pass this program
  170.                              possible icons as parameters you must include
  171.                              a special char sequence in the command line, as
  172.                              explained below.
  173.  
  174.  
  175.    Line 3 : Sync/Async     :   This will be either an "A" or an "S" char to
  176.                              indicate A)synchronous or S)ynchronous execution
  177.                              mode (see below).
  178.  
  179.    In the distribution archive you can find an example of the 'AddToolsData'
  180. configuration file.
  181.  
  182. -2.2- Synchronous vs. Asynchronous mode
  183.  
  184.    If, in the third line of a menu item definition, you s